Alpha TransForm Analytics Guide

Introduction

Dashboards are a new way to analyze form data in TransForm Central. Create Charts, Lists, or fully custom visualizations from scratch to gain new insights, identify patterns, or track metrics with Alpha TransForm.

Accessing Dashboards

Dashboards can be found on the new Dashboard tab in TransForm Central located to the left of the Home tab.

Only users who have been assigned the Management Console role will be able to access dashboards. You can change a user's roles on the Home tab in User Management > Manage User Roles. Select the user you want to give access to Management Console, then hold the Ctrl key down while clicking the Management Console role. Then click Set Roles. See Manage User Roles to learn more.

Overview of Dashboard Tab

Dashboards can be created and managed using the options found in the Dashboard Toolbar.

Dashboard Toolbar

On the left-hand side of the toolbar, the dashboard's name followed by a down arrow is displayed. When you click the dashboard's name, the List of Dashboards is shown. Here you can choose which dashboard to display by selecting it from the dashboard list.

List of Dashboards

Clicking the hamburger menu icon in the upper left-hand corner open the List of Dashboards menu, which contains the following options:

Add Dashboard

Creates a new dashboard in My Dashboards.

Duplicate Dashboard

Creates a copy of the current dashboard and adds it to My Dashboards.

Delete Selected Dashboard

Deletes the current dashboard.

Make Dashboard Shared

Copies the current dashboard to Shared Dashboards.

Save Shared Dashboards Only

Saves all shared dashboards. Note: This is the only way to save shared dashboards.

Auto-Refresh

Puts the dashboard into automatic update mode. In this mode, the navigation bar is hidden and only the dashboard is shown. The dashboard is automatically refreshed every 15 minutes.

Import/Export Dashboard Definition

Opens a text window containing the JSON definition for the dashboard. To export, copy the JSON from the window. To import, replace the JSON in the window with another exported dashboard definition.

Import/Export Predefined Tile Definitions

Opens a text window where you can add your own Tile template definitions shown when adding a new Tile.

At the bottom of the List of Dashboards window, you'll see two informational messages that indicate the last time the dashboards and form types have been refreshed as well as several buttons:

Refresh Dashboards

Refreshes the List of Dashboards, including any modifications to the Shared Dashboards in the TransForm account.

Reorder selected row

Use the up and down arrows to reorder dashboards in the list within the section they are found.

Refresh Form Type Definitions

Fetches an updated list of Form Type definitions for the account. You only need to click this button if you've created a new Form Type on the Designer tab while the Dashboard tab was open and want to reference the new Form Type in your dashboards.

In the Dashboard toolbar to the right of the dashboard's name, you'll find the following options:

Edit

Opens the Dashboard Editor to edit the Dashboard's Name, Filter, Sort criteria, and User Inputs.

Click to save modified info about all your dashboards to the server

This orange message is shown when the dashboard contains modifications that need to be saved. Clicking the message saves your dashboards. If the dashboard is a Shared Dashboard, you must also save the Shared Dashboards to the server separately. See Sharing Dashboards below to learn more.

Refresh

Fetches the form data for the Dashboard. Forms are not automatically downloaded, so you need to do a refresh to get new form data.

Export

Exports the Dashboard as an HTML or PDF document. The exported dashboard can optionally be emailed.

Show List

Displays the list of forms for the Dashboard in a list similar to Management Console.

Help

Opens the help pane.

Account Usage Dashboard

The first time you visit Dashboards, you'll be shown the Account Usage dashboard. The Account Usage dashboard displays usage metrics for all forms in your TransForm account. The dashboard includes a mix of Text and Chart Tiles to show information about forms for the account, including latest submissions by user, the types of forms submitted in the last quarter, the number of forms that contain errors, daily form submissions, and a breakdown of forms by status.

Account Usage Dashboard

You can make modifications to the Account Usage dashboard, but they cannot be saved unless you make a duplicate copy of the dashboard in your account. This can be done using the Duplicate Dashboard in the List of Dashboards.

1. Click Account Usage Dashboard in the dashboard toolbar, then click the icon to the left of "List of Dashboards".

2. Next, click Duplicate Dashboard.

3. The new copied dashboard will open. Click Click to save modified info about all your dashboards to the server to save the dashboard.

The filter that determines what forms are used to generate the summary data shown in the Tiles is defined in the dashboard's filter. You can customize the dashboard filter using the Edit button. Edit opens the Customize Dashboard Filter window where you can change the dashboard name and define filtering and sort rules for the forms.

Customize Dashboard Filter window - Properties

You can also define User Inputs in the Customize Dashboard Filter window. User Inputs can be used to create dynamic filters that change what forms are downloaded for the dashboard. For example, a user input could be used to filter on specific form types. When a User Input is changed, you may need to click the Refresh button in the dashboard toolbar to update the forms for the dashboard.

Dashboard User Inputs

A preview list is located at the bottom of the Create Dashboard Filter window. The preview lists the forms that have been retrieved for the dashboard based on the filter rules. Click the Refresh button to update the preview with the new forms list if you modify the filter.

Preview listing the forms for the dashboard

Clicking Show List in the dashboard toolbar opens a list view of the forms. All forms downloaded for the dashboard are shown in the list. The columns for the forms list can be customized by clicking the pen icon next to the + in the upper right corner. You can perform the same actions here as you can in the Management Console, including exporting forms or assigning forms to a user.

List of forms associated with the dashboard

Information about the forms is shown in the dashboard using Tiles. There are three types of Tiles: Chart, List, and Text. A Chart Tile plots form data, e.g. aggregate or discrete values, as a chart, such as a bar or line chart.

A bar chart

List and Text Tiles use templates to generate a list of forms or a custom visualization.

A Text Tile

Tiles can be clicked to view the subset of forms used to generate the visualization. For example, clicking a donut chart segment displays all forms associated with the segment.

Left: A donut chart. Right: The list of forms associated with the "closed" segment of the donut.

Tiles can also have user inputs to add local filtering. Tile user inputs automatically update the Tile when they're changed. User inputs can be added to filter a Tile, such as showing a single type of form or forms created within a specific time frame.

A line chart with a date navigation User Input

Creating Dashboards

Dashboards are built with Tiles. When you create a new dashboard using the Add Dashboard option in the List of Dashboards menu, a new blank dashboard is created with one Tile, the Number of Forms Tile. The Number of Forms Tile displays the number of forms retrieved for the dashboard.

All dashboards are required to have at least one Tile. If you delete all Tiles from your dashboard, the Number of Forms Tile is automatically added.

Creating Tiles from Templates

To create a new Tile, click the icon in the upper right corner of any Tile. Then, select Add New Tile.

Tile menu

The Add New Dashboard Tile window will appear.

Select the type of Tile you want to add. There are three basic Tile types: Chart, List, and Text. In addition, the Add New Dashboard Tile includes some pre-built templates:

Blank Chart Tile

A blank Chart Tile. Chart Tiles can be used to create Line Charts, Bar Charts, Pie and Donut Charts, Polar Charts (i.e. Radar Charts), Area Charts, Stacked Charts, and Scatter Plots. Chart Tiles can also be used to create a basic List of forms.

Blank List Tile

A blank List Tile. List Tiles displays each form in a List using a layout defined using TPL.

Blank Text Tile

A blank Text Tile. Text Tiles are freeform Tiles that are defined using TPL templating.

Number of Forms Tile

The Number of Forms Tile, which is automatically added to all new dashboards.

Forms by Month Tile

A bar Chart Tile that displays the total number of forms created each month for the current year.

Forms by Month and Status Tile

A percent bar Chart Tile that displays the number of forms by month grouped by status (e.g. open, closed) for the current year.

Form Counts with Date Navigation Tile

An area line Chart Tile that displays the number of forms created each month. The form counts are displayed for each day of the month. The template includes a User Input that lets you change the month for which form counts are shown.

Form Types with Sorting Tile

A list Chart Tile that displays a list of forms types for the account and the number of instances for each form type.

Account Usage Tile

A Text Tile that displays a list of users, the number of forms assigned to them, and when they last submitted a form.

Select the Forms by Month Tile (Forms by Month) template from the list to add it to the dashboard. The Tile editor will open after the Forms by Month Tile is added to the dashboard, giving you the opportunity to edit the Tile immediately after creating it.

Tile editor

The Tile editor has 4 tabs:

Properties

Here is where you can configure the look and feel of the Tile. This includes specifying the type of Chart to use (Line, Bar, etc) as well as the templates for List and Text Tiles.

Filtering

Add additional local filters applied locally to the dashboard's forms. See Filtering below to learn more.

Sort Order

Custom sorting applied locally to the forms before they're displayed in the Tile. See Sort Order below to learn more.

User Inputs

Custom controls you can add to the Tile to add dynamic filtering (such as changing the month or form type shown) and sorting. User Inputs can also be referenced in some properties where TPL is used. See User Inputs below to learn more.

To the right of Tile editor tabs is the Tile Type property, which you can use to change the Tile's type. In addition to Tile Type, all Tiles have Tile Size properties that define the Tile's Width, Height, and whether or not the Tile Always starts on a new row. All Tiles also have an advanced TPL Functions section where you can define functions to use in properties, templates, filters, or sort order rules that support TPL. See Extensibility with TPL below to learn more.

A preview of the tile is shown on the right side of the Tile editor. When you hover your mouse over the tile, the preview is enlarged. You can enable or disable automatic updating of the preview using the Auto-Preview checkbox below the list of Properties.

In the title bar for the Tile editor on the right hand side are three buttons: Import/Export, Save, and Cancel. Save saves changes made to the Tile after it was added and closes the Tile editor. Cancel reverts the Tile to its original template definition and closes the Tile editor. Import/Export can be used to import or export a Tile. See Exporting Dashboards and Tiles below to learn more.

Creating Blank Tiles

Blank Tile templates can be used to add a Chart, List, or Text Tile with no other predefined settings. Depending on the type of visualization you want to create, starting with a blank Tile may be easier than trying to change one of the other Tile templates to suit your needs.

Tiles are configured using properties to customize the data display. Chart Tiles convert Form data into graphical displays. For example, Forms by Month displays a count of forms created each month for the current year as a bar chart.

• Processing Type

  Creating a Chart begins with the Chart Type, Data Source, and Processing properties. The Value Processing Type describes how to transform your form data into a format that can then be used to create a chart. Types of data processing include:

  • Count of each different discrete X value - e.g. the number of forms by status (open, submitted, approval, and closed).
  • Sum of numeric Y values
  • Average of numeric Y values - e.g. the average 5S Audit score (Y) each month (X).
  • Minimum of numeric Y values - e.g. the lowest 5S Audit score (Y) each week (X).
  • Maximum of numeric Y values - e.g. the highest 5S Audit score (Y) each week (X).
  • Discrete X values, numeric Y values - e.g. the 5S Audit score (Y) for the most recent form submitted by each user (X).
  • Continuous numeric X and Y values - e.g. daily temperature readings.
  • TPL calculates all charting data - see Extensibility with TPL below.

  When charting data, it's important to understand the difference between discrete and continuous data.

  Discrete data is data that can only have very specific values from a fixed set of choices. Form Status is an example of a discrete value. Alpha TransForm includes four basic status: "open", "submitted", "approval", and "closed". A form's Status can only be one of these options. Bar charts, pie charts, donut charts, and radar charts can be used to display discrete data values.

  Continuous data is data that can have any value that cannot be enumerated as a fixed list of choices. Measurements are an example of continuous data, e.g. a temperature reading. Line charts and area charts are often used to display continuous data.

  After choosing the Processing Type that accurately describes the type of data you plan to chart, select the Source of the Data. Unless you plan on writing TPL to calculate the entire chart, Specific fields from each form should be selected. Finally, choose a Chart Type and then open the Graph X properties.

  Experiment with different Chart Types after you've finished configuring your X, Y, and Group data.

• X Values

  Graph X properties define what data to chart. In the case of Pie and Donut charts, only the X value is plotted. All other charts support both an X and Y value. To configure the X value, first select one of the How To Specify Value options:

  • Choose From Field List - Select the field from the Form data.
  • Graph Multiple Numeric Data Fields - Allows you to graph multiple data points.
  • Graph Multiple Discrete-Value Data Fields - Allows you to graph multiple, discrete data points. The Graph Multiple Discrete-Value Data Fields option is for graphing values from List or Button List fields in a form. The List or Button List's possible values must be defined in the Designer. If the options for field are populated using TPL, the Search/Add option for the field is set to "Search & Add custom", or the field is not a List or Button List field, Graph Multiple Discrete-Value Data Fields cannot be used to graph the field's data.
  • TPL Expression - See Extensibility with TPL below.

  For example, to create a Pie chart displaying a count of form status, you would select Choose From Field List and set Graph X to "Status" from the list of fields.

  

  Specifying X values

• If you want to chart a field specific to a form type, select the form type from the Specify an optional Form Type whose field names will appear in choice lists below dropdown. This will add fields from the form definition to the list of Graph X choices.

  

  Selecting a Form Type

• Clustering

  You can optionally group form values together using Clustering. For example, clustering can be used to display a count of forms created by week. Graph X in this scenario is set to the Created field. The following options are available for clustering:

  • Year - cluster data together by year.
  • Month - cluster data together by month.
  • Day - cluster data together by day.
  • Day of week - cluster data together by day of week (Monday, Tuesday, etc).
  • Custom

  Graph X must be set to a date or date-time field if one of the date clustering types is chosen. The Custom option can be used to write your own clustering criteria. Custom doesn't require the X value to be a date. The Custom method uses a test:value syntax separated by commas to define each cluster. For example, assume X can be any value from 1 to 100 and you'd like to cluster X into three categories: low, medium, and high. Your custom clustering definition would be:

  <35:low,<=75:medium,<=100:high

• Y Values

  The next step is to specify your Y values, if they apply to the Processing Type. The Graph Y properties are similar to the Graph X. The Y value is the data you want to plot along the Y axis of the chart. Here is where you would specify multiple values if you wanted to chart multiple data points over X. For example, the chart below plots the average 5S Audit scores (Sort Score, Set in Order Score, Shine Score, Standardize Score, and Sustain Score) for each audit category per month (Audit Date clustered by Month).

  

  Graphing Multiple Y Values

• Grouping and Chart Colors

  Chart values can be divided into groups using Grouping. The Group specification can be a field from the form or custom TPL. For example, a chart showing the number of forms created each month could be grouped by status:

  

  A stacked bar percent chart displaying monthly form counts grouped by status each month

• The colors used in the chart are also defined in the Group settings in Group Colors. If defined, the colors will be used in the order specified. Colors are defined as a comma-delimited list of CSS color values. For example, the colors for the chart above were specified as:

  #198038,#f1c21b,#ff832b,#da1e28

• Titles, Labels, and Legends

  Data and axes labels, titles, legends, and other chart settings are configured in Titles, Labels, and Legend. Here you'll find settings to adjust margins, rotate X and Y axis labels, create threshold lines for line and bar charts, and more. Note that some settings may not apply to your chart type (e.g. pie charts do not have threshold lines).

List Tiles

List Tiles are defined using TPL. The TPL Template for the List Tile is applied to each row of data. List Tiles are well suited for creating lists of information. You use the same metadata and form field placeholders as those used in when adding TPL to Form Designs. For example:

Created: {$#created}, Form ID: {$#formid}

The List Tile TPL Template also has access to the $dash dashboard system variable, which contains additional information. See Extensibility with TPL to learn more about defining TPL Templates for List Tiles.

A List Tile

An optional Heading and List Title for the Tile can be specified in Titles. The Heading is shown at the top of Tile while the List Title is shown to the left above the list.

Location of Heading and List Title labels

As with Chart Tiles, you can click a row in a List Tile to view the associated form.

Text Tiles

Text Tiles are also defined using TPL. The TPL Template for Text Tiles is given all of the dashboard data, which can be accessed using the $dash system variable. For example, the template below displays a count of all forms for the dashboard:

Number of Forms:<br>{len($dash.rows)}

Template Action defines what happens when the user clicks the Text Tile. This is different from List and Chart Tiles which automatically display a subset of forms when clicked. The template action for the Text Tile can display all forms for the dashboard or a filtered list of forms, which is determined by the Filtering rules for the Tile. If no action is specified, nothing happens when the Tile is clicked.

You can alternatively add actions to the TPL Template using a5-items. See Extensibility with TPL to learn more about creating Text Tiles.

Filtering

The Filtering tab is available in both the Dashboard properties and the Tile properties and is used to define a set of Filter rules which generate the list of Forms that comprise the source data for the Dashboard or Tile. Filter rules defined at the Dashboard level operate against all forms in your account. Filter rules defined at the Tile level operate against the results of the Dashboard filter. This allows you to have tiles that show subsets of your dashboard data.

Create a new Filter rule using the + button below the filter list. Filter rules can be reordered using the up and down arrow buttons and deleted with the X button. Filter rules are applied against each Form in the order listed. The Form must pass all rules in order to be included in the resulting source data set. Filter rules may be contained within a group by using the grouping button (). A Filter group may be set to require all rules contained within to match or any rule to match. This allows creation of AND/OR rules.

A Filter rule takes a Field to test on, a test, and a value to test against.

The Field to test may be one of the top-level Form fields, such as Form ID, or any of the form data. Select form data fields by choosing the Form Type from the dropdown list. The form's fields will then display within the "Field" dropdown.

The following Tests are available:

• Less Than - The field is less than the specified value.
• Less Than or Equal - The field is less than or equal to the specified value.
• Equal - The field is equal to the value.
• Not Equal - The field is not equal to the value.
• Greater Than - The field is greater than the value.
• Greater Than or Equal - The field is greater than or equal to the value.
• Is One of the Items in a List - The field is one of the items in a List of values.
• Between - The field is between two values.
• Not Between - The field is not between two values.
• Is NULL - The field has no value.
• Is NOT NULL - The field has a value.
• Starts With - The field starts with the specified value.
• Ends With - The field ends with the specified value.
• Contains - The field contains the specified value.
• Does Not Start With - The field does not start with the specified value.
• Does Not End With - The field does not end with the specified value.
• Does Not Contain - The field does not contain the specified value.
• Equal (case-sensitive) - The field is equal to the value, ignoring case.
• Not Equal (case-sensitive) - The field is not equal to the value, ignoring case.
• During a Relative Time Period - The field occurs during a date-time period. E.g. during the last month.
• Not During a Relative Time Period - The field does not occur during a date-time period.
• During a Relative Time Range - The field occurs during a custom date-time period.
• Not During a Relative Time Range - The field does not occur during a custom date-time period.

The Value Type dropdown contains a list of options for specifying the value to use in the test. These options are dependent on the test type.

• Typed Text - The value is entered as static text into the Filter rule.
• Field or User Input - The value is selected from a list of Form metadata, Form data (if a Form Type has been selected), or User Inputs defined.
• Item From A List - Certain fields, such as Form ID can have their value selected from a list of predetermined values.
• Date/Time - The value is selected from a timestamp picker control.
• Date - The value is selected from a date picker control.
• Time - the value is selected from a time picker control.
• User Input - The value is selected from the list of User Inputs defined.
• Relative Period - The value is selected from a list of relative time periods.

A Filter rule can be enabled or disabled as well as enabled based on User Input selections. This allows you to create Dashboards and Tiles where the user can change the source data interactively, such as to filter based on product type.

Advanced Filtering

• Data Groups

  Filter rules can be created which evaluate form data located within top-level Data Groups. Use the magic wand button to open the menu of advanced filter rules to select one of the data group filters:

  • Data Group Field "Any" Row - Include the Form if any Data Group entry matches the Filter rule.
  • Data Group Field "All" Row - Include the Form if all of the Data Group entries match the Filter rule.

• Extra Server Processing

  Extra Server Processing is an advanced filtering option used to customize the form data returned from the server. As the name suggests, the options defined here are executed on the server before form instance data is sent to the browser for use in Tiles or other filter criteria executed client-side (e.g. filtering rules defined for form fields such as the "city" field for an inspection form.)

  Extra Server Processing includes an option to specify what data is returned from the server. The default is Data Rows (recommended), which returns all form instance data matching the filter. Only Count returns the total number of forms that match the filter. Only Count is ideal when fine-tuning filter criteria to improve a dashboard's performance. Because Only Count does not result in any form data being returned, it's recommended that it should only be used when optimizing dashboards.

  Data to Fetch Options

  Description

  Data Rows

  (Default) All form data matching the filter expression is returned.

  Only Count

  A count of the number of forms that match the filter is returned.

  Optional TPL script can be added in Extra Server Processing to perform additional filtering or add custom columns to the form data. TPL scripts can be run before and after form data filtering (filter rules applied to form fields, e.g. City contains "Springfield").

  Your TPL script can reference the following server variables:

  • $dash.servervalues.userinputs - This variable contains User Inputs defined in the Dashboard. This variable does not include User Inputs defined in tiles. This variable is only available in Extra Server Processing.
  • $dash.servervalues.sqlrowcount - This variable is the number of forms that match the Dashboard filter. This variable is available to Tiles.
  • $dash.servervalues.rows - This variable contains the form data that matches the Dashboard filter. This variable is only available in Extra Server Processing.

  Extra Server Processing is not used by Show List. Show List fetches all matching form instances.

Sort Order

The Sort Order tab is available in both the Dashboard properties and the Tile properties and is used to define a set of Sort rules that apply to the list of Forms included in the Dashboard or Tile's Filter.

Create a new Sort rule using the + button below the rule list. Sort rules can be reordered using the up and down arrow buttons and deleted with the X button. Sort rules are applied in the order listed against the list of Forms for the Tile or Dashboard.

Sort rules take a field to sort on, such as Created, and a sort direction:

• Up - String / Alphabetic sort A-Z.
• Down - String / Alphabetic sort Z-A.
• Up (numeric comparisons) - Ascending numeric sort.
• Down (numeric comparisons) - Descending numeric sort.

A sort rule can evaluate form data by choosing the Form Type from the dropdown list. The form's fields will then display within the "Field To Use For Sort" dropdown.

Sort rules can be enabled and disabled as well as enabled based on User Input selections. This allows you to create Dashboards and Tiles where the users can change the sorting interactively.

Sort Order tab

User Inputs

User Inputs allow Dashboards and Tiles to be interactive. User Inputs can be used in Filter and Sorting rules, to control other User Inputs, and in custom TPL extensions.

Stacked Bar Chart with several User Inputs

User Input Types

Text

Contains arbitrary typed text.

Date

Contains a date string in YYYY-MM-DD format. Provides a calendar date picker control for the user to select a date.

Date/Time

Contains a timestamp string in YYYY-MM-DD HH:MM:SS format. Provides a calendar and time picker control for the user to select the date and time.

Relative Date

Relative Dates refer to time periods relative to the current date, such as This Month, Today, or Last Year. Relative Dates are stored in a format that contains the relative period, such as day or month, and a numeric value indicating the number of periods before or after the current period. For example, week:-2 represents two weeks prior to the current week.

Relative Date User Inputs can be set in two different ways:

• Button List - Presents the user with a set of buttons of common relative date selections. You can select which relative date options are displayed.
• Adjustable Periods - Provides the user the ability to navigate forward and backwards through a relative date period. You must specify which period length to use. For example, you can give the user the ability to navigate forward and backward by months.

List

Presents a list of choices for the user to select from. Only one choice may be selected at a time. Lists can have an arbitrary number of choices defined. Lists can be displayed to the user as either a Button List or a Dropdown.

Checkbox

Displays a single checkbox that contains "Y" when checked and "" when unchecked.

Heading Only

Contains no data but is used to display a text label within the User Input area of the Dashboard or Tile.

Extensibility with TPL

While the majority of Dashboard uses can be configured by setting various properties, Alpha TransForm Analytics includes a number of areas where things can be extended by using TPL templates and scripts. This allows the development of fully customized data visualizations.

Dashboard System Variables

TPL scripts in Dashboards and Tiles have access to special system variables to allow for calculations. These variables are all part of a $dash system object. The $dash top-level object will have different properties depending on where it is being invoked.

TPL Templates

TPL Templates in TransForm Analytics operate the same way they do in the form designer. TPL templates may be used in several places:

• In Text Tiles, a TPL template defines all of the content for the tile.
• In List Tiles, a TPL template defines the content for a row of the source data and is repeated for each row.
• In Tile labels and titles, TPL expressions may be used to provide dynamic content.

TPL Templates have access to special system variables to allow for calculations.

• $dash.rows - the filtered list of rows for the Tile
• $dash.allrows - the unfiltered list of retrieved rows in the Dashboard
• $dash.tileuserinputs - object with a property for each User Input on the Tile
• $dash.dashboarduserinputs - object with a property for each User Input on the Dashboard
• $dash.tilenum - the order (0-originated) of the Tile on the Dashboard
• $dash.rowindex - in List tiles, the index of the row in $dash.rows being processed
• $dash.listingdetails - in List tiles, the row's listing details value
• $dash.tileheight - in Text tiles, the approximate height in pixels of the tile body without user inputs
• $dash.row - in List tiles, the row being processed. The row contains the retrieved form instance data, including:
  • ID
  • formid
  • forminstanceid
  • formversion
  • status
  • person
  • created
  • completed
  • haserrors
  • missingrequired
  • formdata
  • timestamp
  • user1,user2,user3,user4,user5
  • userlabel1,userlabel2,userlabel3,userlabel4,userlabel5
  • duedate
  • displayname - the user's display name for the person field. This value is available after a short delay after opening the Dashboard tab.
  • formdatajson - an object with the JSON.parse of the formdata field

See TPL Templating and TransForm Programming Language Overview for more info about TPL.

TPL as Chart Source Data

TransForm Analytics allows the source data for a Chart to be calculated using a TPL script rather than specifying fields from the list of Forms. This is done by selecting "All calculated using TPL (advanced)" option in the Chart Type, Data Source, and Processing property of the Chart Tile. Using this option, a TPL script must return an object containing the chart data and other parameters used by the Chart.

The object returned should have the following properties:

rawdata

(required) an array of objects with the following values

x

(required) the x-axis data for the Chart

y

(optional) the y-axis data associated with the x value

g

(optional) the group associated with the x value

pos

(optional) comma separated list of the index values of Forms to display when the data point is clicked

values

(optional) an array with the text of the x-axis labels corresponding to the x-axis data points defined in rawdata. The Tile will provide its own values if left blank.

nopsvalue

(optional) when set to a non-blank value, overrides the default behavior of using the original row index values as a list of Forms to display when clicked, if rawdata.pos is not defined.

When debugging, the Collected Data tab when Show Intermediate Data is checked will show the X, Y, Group and Pos (Form) data generated.

Here's an example of using TPL to source the raw data:

d=array()
for i = 0 to len($dash.rows)-1
    row=$dash.rows[i]
    r=obj()
    r.x = row.formdatajson.placeborn
    arrayPush(d,r)
endfor
return obj("rawdata",d)

List and Text Tile Templates

When adding a TPL Template to a List or Text Tile, the following a5-item values may be used to run actions:

a5-item="examineFiltered:spec" where "spec" may be "all" for all rows of the tile, or a comma-separated list of one or more 0-origined numbers to indicate which Tile rows should be shown in the Forms List.

Using examineFiltered also requires the a5-tile="{$dash.tilenum}" attribute to identify which tile the a5-item is being called. "{$dash.tilenum}" is a variable identifying the current Tile dynamically, rather than statically coding the Tile number. This lets you reorder Tiles without having to update the template with the new Tile number. For example:

<div a5-item="examineFiltered:{$dash.rowindex}" a5-tile="{$dash.tilenum}">View Yesterday's Forms</div>
<div a5-item="examineFiltered:all" a5-tile="{$dash.tilenum}">View all Forms</div>

a5-item="examineFull:spec" is similar to examineFiltered, but refers to the list of forms retrieved for the dashboard. It does not require a5-tile because no information about the Tile is needed to determine the Form List.

Pre-processing Chart Data

After the Chart data is sourced, whether via selected fields or calculated by custom TPL, the data may be modified before it is run through the processing selected in the Value Processing Type dropdown. By setting the Do pre-processing on the data using TPL property to Yes, you can enter TPL code to modify the Chart data.

The pre-processing TPL code is given $dash.data containing an array of all collected data rows generated by the Dashboard and Tile Filter and Sort rules. The code must return an object with the following attributes:

data

(required) an array of the modified data rows (in the same format as the rawdata attribute in Chart data sourcing above)

values

(optional) an array with the x-axis values to override the automatically generated values

gvalues

(optional) an array with the group values to override the automatically generated values

nosortxlabels

(optional) if present and not blank, suppresses any alphabetic sorting of the x-axis values

When debugging, the Pre-Processed Data tab when Show Intermediate Data is checked will show the X, Y, Group and Form data generated.

Here is an example of TPL to pre-process the data and remove all rows that do not have a value defined (which is different than a value of "" in the raw data):

return arrayFilter($dash.data, "x isdefined")

Processing Chart Data

After the Chart data is sourced and potentially modified during the pre-processing phase it is processed for charting. The Value Processing Type property contains a list of preset processing methods, such as Sum of Numeric Y Values. For custom use cases the Chart data may be generated using TPL by selecting the option "TPL calculates all charting data."

The TPL code is given $dash.rawdata which is an array of the pre-processed, source data. The code must return an object with the following attributes:

data

(required) array of objects with the following attributes:

x

(required) the x-axis value for the row.

y

(optional) the y-axis value for the row.

z

(optional) the group value for the row.

attrs

(optional) comma separated list of row indexes for the forms to display if the chart data point is clicked.

values

(optional) Like the pre-processing object, returns a list of x-axis labels to use instead of the automatically generated ones.

When debugging, the Processed Data tab when Show Intermediate Data is checked will show the X, Y, Group and Attrs (Form) data generated.

Here is an example of TPL processing similar to "Count of each different discrete X value", calculating both the Y value and the list of values encountered:

r = obj()
raw = $dash.rawdata
totals = obj()
vals = array()
for i=0 to len(raw)-1
    val = raw[i].x
    if totals[val]
        totals[val] += 1
    else
        totals[val] = 1
        arrayPush(vals, val)
    endif
endfor
r.data = array()
for i=0 to len(vals)-1
    r.data[i] = obj()
    r.data[i].x = vals[i]
    r.data[i].y = totals[vals[i]]
endfor
r.values = vals
return r

Post-processing Chart Data

After the Chart data processing the data may be further modified prior to rendering the chart. By setting the Do post-processing on the data using TPL property to Yes, you can enter TPL code to modify the Chart data.

The post-processing TPL code is given $dash.data and $dash.values containing the Chart source data as generated by the Value Processing rule. These objects may be modified directly or a new object with data, values, gvalues, and nosortxlabels attributes may be returned.

In addition to the standard "x", "y", "g", and "attrs" attributes of $dash.data, the following optional attributes may also be set:

tip

text to show as a tooltip when hovering over the data point. The \n character may be used to insert a carriage return.

fillcolor

An HTML RGB color (like #FF0000) to use as the fill color for the data point.

linecolor

An HTML RGB color (like #FF0000) to use as the line color for the data point.

linewidth

a number used to set the width of the line used to draw the data point.

size

a number used to set the size of the drawn data point.

shape

the text name for the shape to use for the point marker on a scatter or line chart. Possible values are:

• dot - a circle
• bar-v - a vertical bar
• bar-h - a horizontal bar
• bar-bltr - a diagonal bar from bottom-left to top-right
• bar-tlbr - a diagonal bar from top-left to bottom-right
• diamond - a diamond
• square - a square
• square-round - a square with rounded corners
• x - an x-shape (two diagonals)
• cross - a + shape (horizontal and vertical)
• tri-b - a triangle pointing down
• tri-t - a triangle pointing up
• tri-r - a triangle pointing to the right
• tri-l - a triangle pointing to the left

label

HTML to use as the data point label, if enabled on the chart.

value

for charts with multiple discrete fields, contains the raw value of the choice list.

vname

for charts with multiple discrete fields, contains the display value of the choice list.

When debugging, the Post-Processed Data tab when Show Intermediate Data is checked will show the X, Y, Group and Form, Label, Tip, Value/VName and Line/Fill/Width/Size/Shape data generated.

Here is an example of post-processing to add tooltips with the value:

d = $dash.data
for i=0 to len(d)-1
    di = d[i]
    di.tip = "The value is:\n" & di.y
endfor

Define Chart X, Y, and Group Data as TPL Expression

Instead of calculating all Chart data using TPL, the individual Graph X, Graph Y, and Graph Group data may be calculated using the option "TPL Expression (Advanced)" in the How To Specify Value dropdown of each corresponding property. Individual data points in multiple discrete-value and multiple numeric-value types may also be specified as a TPL expression. Any clustering methods specified will also be automatically applied to the values generated by the TPL expression. This allows you to use the regular data source options and just tweak individual values as needed.

TPL expressions entered into the TPL For X/Y/G Value box are evaluated once per row in the filtered source data for the Tile. The TPL expression must return the value to use for the corresponding chart data for that row.

TPL expressions for the Chart X, Y and Group data have access to the $dash.rows object of source data. $dash.rowindex is the 0-originated index of the current row being processed. Other system objects are available as they are for the List Tile TPL Template. See TPL Templating for more info.

Here is an example of using a TPL expression for the Graph Group to group results by the domain name of the user submitting the form:

return split($dash.rows[$dash.rowindex].person,"@")[1]

Custom Filter Rule

You can create custom filter rules using TPL code. To create a new Custom TPL Code filter rule, click the magic wand icon and select "Add TPL Row." Enter TPL code into the window provided. The code will be executed against each row and the last statement should result in "" to exclude the row, or any other value to include the row. Form data can be accessed using # notation (#field1) and will be left empty if the form type does not include a field with that name.

• Examples

  Only include rows with forms that have a field1 field with a value:

  #field1

  Only include rows with forms that have a field1 field and that value is greater than 50:

  #field1 > 50

TPL Functions

You can create your own TPL functions at the Dashboard and Tile level. These functions can be called in your TPL templates and scripts.

TransForm Analytics also has several new functions you can call in your dashboard TPL code:

• chartGauge(value,title,color,max)

  Creates a gauge display that can be embedded anywhere TPL Templating is supported.

  

  A gauge chart

• HTMLesc(string)

  Escapes special characters like "<" and "&" so they render as characters and are not treated as HTML markup when output from a TPL template.

• metaDataGet(fieldname)

  Returns the value of a metadata field, including user* and userlabel* metadata fields.

• logConsole(string)

  Logs output to the browser console window as a debugging aid in debugging Dashboard processing TPL. Calls to logConsole() should be removed from your TPL templates when they are no longer needed.

Sharing Dashboards

Shared Dashboards are dashboards available to all users in a TransForm account. Shared dashboards can only be edited and saved by users who have the Administrator role. Any existing dashboard in the My Dashboards list can be shared using the Make Dashboard Shared option in the List of Dashboards menu. When selected, the current dashboard is copied and added to the Account Shared Dashboards list.

List of Dashboards

After creating the shared dashboard, it then needs to be uploaded to the TransForm account using the Save Shared Dashboards Only option from the List of Dashboards menu. Shared dashboards are only updated on the TransForm account when Save Shared Dashboards Only is used. Aside from this extra step required to save a shared dashboard, editing and managing a shared dashboard is the same as editing dashboards listed in My Dashboards.

Exporting Dashboards and Tiles

Exporting is another way to share a Dashboard or Tiles. The advantage of using export over sharing is that all or part of a Dashboard can be shared with a smaller group of TransForm users while Shared Dashboards are available to every user who has access to Dashboards for the TransForm account.

You can export Dashboards and Tiles using the Import/Export Dashboard Definition menu option in the List of Dashboards menu or the Import/Export button in the Tile editor. Dashboard and Tile definitions are exported using a JSON format. This JSON format can be used to copy visualizations between Dashboards for different TransForm accounts.

Exported Tile definitions can also be used to customize the Tile templates shown in the Add New Dashboard Tile dialog. Tile templates are created using Import/Export Tile Predefines. Custom Tile templates replace the system templates shown when adding a new Tile.

Tile templates are defined using JSON, as show in the sample Tile Predefines definition below:

[
    {
        "id":"template1",
        "title":"Text Box",
        "description":"Shows the number of forms retrieved.",
        "image":"http://abcxyz.s3.amazonaws.com/template1.png",
        "item":{
            "itemtype":"template",
            "width":"S",
            "height":"S",
            "rowtemplate":"{len($dash.rows)} Form Instances Selected",
            "templateaction":"showfilteredlist",
            "filter":{"main":[],"sort":[],"variables":[],"variablevalues":{},"tplfunctions":""}
        }
    }
]

id

The Tile template id. This should be unique among all Tile templates in the Tile Predefines definition.

title

The template title.

description

The template description.

image

An optional URL for an image to show for the Tile Template. The image needs to be hosted on a third-party service that can be accessed by TransForm Central.

item

A JSON object containing the Tile definition. This is where you place the JSON exported from a Tile.

To save Tile Predefines, you must use the Save Shared Dashboards Only option to upload the templates to the TransForm account. Because Tile Predefines affect the entire TransForm account, they can only be created and saved by a user with the Administrator role.